// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

/**
 * 正则表达式模式。
 *
 * 正则表达式是一种模式([Pattern])，可以用来匹配字符串或字符串的一部分。
 *
 * Dart正则表达式与JavaScript正则表达式一样，具有相同的语法和语义，
 * 可参见JavaScript正则表达式的规范
 * <http://ecma-international.org/ecma-262/5.1/#sec-15.10>
 *
 * [firstMatch]是最重要的实现方法，它将一个正则表达式应用到字符串，并返回第一个匹配[Match]。
 * 在[RegExp]中，其他所有的方法都能基于该方法构建出来。
 *
 * 使用[allMatches]查找一个字符串中正则表达式所有的匹配。
 *
 *     RegExp exp = new RegExp(r"(\w+)");
 *     String str = "Parse my string";
 *     Iterable<Match> matches = exp.allMatches(str);
 *
 * 请注意原始字符串（使用`r`作为字符串的前缀）的使用。
 * 在上面的例子中，使用原始字符串将字符串中的每个字符视为原义字符。
 * 否则，`\`将被视为转义符。
 */
abstract class RegExp implements Pattern {
  /**
   * 正则表达式的构造函数。
   *
   * 如果[source]不是有效的正则表达式语法，将抛出异常[FormatException]。
   */
  external factory RegExp(String source, {bool multiLine: false,
                                          bool caseSensitive: true});

  /**
   * 在字符串[input]中，查找正则表达式的第一个匹配。
   * 如果没有匹配，返回`null`。
   */
  Match firstMatch(String input);

  /**
   * 返回一个可迭代对象，包含对于字符串[input]的所有正则表达式匹配。
   *
   * 如果设置了参数[start]，会从`start`位置开始查找。
   */
  Iterable<Match> allMatches(String input, [int start = 0]);

  /**
   * 返回在字符串[input]中，正则表达式是否有匹配。
   */
  bool hasMatch(String input);

  /**
   * 返回字符串中[input]，正则表达式匹配到的第一个子字符串。
   */
  String stringMatch(String input);

  /**
   * 创建`RegExp`对象使用的正则表达式源字符串。
   */
  String get pattern;

  /**
   * 正则表达式是否要匹配多行。
   * Whether this regular expression matches multiple lines.
   *
   * 如果正则表达式匹配多行，"^"和"$"字符会匹配每行的开始和末尾位置。
   * 如果不匹配多行，字符匹配输入字符串[input]的开始和末尾位置。
   */
  bool get isMultiLine;

  /**
   * 正则表达式是否区分大小写。
   *
   * 如果正则表达式不区分大小写，它将使用模式中的字母来匹配输入字母。
   * 即使这两个字母是同一个字母，只是大小写不同。
   */
  bool get isCaseSensitive;
}
